17장 로그인 기능 붙이기 (입문판)

원서: 클로드 코드 완벽 가이드, 코드팩토리 최지호

이 장에서 딱 4가지만 1. 로그인 기능을 직접 만들지 말고 빌려 쓰자 — Supabase 가입과 설정 2. 클로드가 최신 사용법을 보게 돕는 도우미 — Context7 MCP 붙이기 3. 클로드에게 "선 넘지 마"라고 말하는 법 — 경계를 정해 로그인 만들기 4. 만든 게 잘 도는지 확인하는 법 — 열쇠 넣고 서버 켜기

이번 장은 "내 웹사이트에 로그인/회원가입 기능을 붙이는" 이야기다. 16장에서 만든 로그인 화면은 아직 그림일 뿐이었다. 버튼을 눌러도 아무 일도 안 일어난다. 이번 장에서 그 그림에 진짜 동작을 채워 넣는다.

1. 로그인 기능을 직접 만들지 말자 — Supabase

이런 적 있죠?

로그인 기능 하나 만들려고 했더니 할 일이 산더미다. 비밀번호를 그냥 저장하면 위험하니까 암호화해야 하고, 누가 로그인했는지 기억하려면 세션이라는 걸 관리해야 하고, "이메일 인증 메일 보내기"도 직접 짜야 한다. "로그인 버튼 하나 만들려는데 왜 이렇게 할 일이 많지?" 하고 막힌 적 있을 것이다.

그게 바로 백엔드(서버 쪽 일)가 어려운 이유다. 그래서 똑똑한 사람들이 "이거 그냥 빌려 쓰세요"라고 만들어 둔 게 있다. 바로 Supabase다.

용어 풀이: Supabase 한 문장 뜻 — 로그인, 데이터 저장 같은 서버 기능을 미리 만들어 빌려주는 서비스다. 일상 비유 — 집을 지을 때 벽돌부터 굽지 않고 이미 만들어진 레고 블록을 조립하는 것과 같다.

용어 풀이: BaaS 한 문장 뜻 — 서버를 직접 만들지 않고 클라우드에서 빌려 쓰는 방식을 말한다 (Backend as a Service). 일상 비유 — 밥을 직접 짓지 않고 배달앱으로 시켜 먹는 것과 같다. 주방(서버)은 남이 운영하고 나는 받아서 쓴다.

비유를 클로드 코드에 연결하면

따라 하기 — Supabase 가입부터 설정까지

차근차근 4단계다. 천천히 따라가면 된다.

1단계 — 가입하기 supabase.com 에 들어가서 Sign Up(가입)을 누른다. 가입하면 Organization(팀/회사 묶음)을 하나 만들라고 한다. 이름은 아무거나, 종류는 Personal(개인), 플랜은 Free(무료)를 고른다.

용어 풀이: Organization 한 문장 뜻 — 내 프로젝트들을 한데 묶는 상위 폴더 같은 것이다. 일상 비유 — 아파트 단지의 "동"이다. 그 안에 여러 집(프로젝트)이 들어간다.

2단계 — 프로젝트 만들기 New Project(새 프로젝트)를 누른다. 방금 만든 Organization을 고르고, 프로젝트 이름을 정한다(예: k-nomad). Database Password(데이터베이스 비밀번호)는 Generate Password(자동 생성)를 누른 뒤 Copy로 복사해 안전한 곳에 꼭 저장한다. Region(지역)은 Northeast Asia (Seoul), 즉 서울을 고른다. Create new project를 누르면 만들어진다.

여기서 가장 중요한 한 가지. Database Password는 이때 딱 한 번만 보여준다. 지금 복사 안 하면 다시 볼 수 없다.

잘못된 예: "비밀번호 나중에 보면 되겠지" 하고 그냥 넘어감 → 나중에 못 찾아서 곤란 올바른 예: 자동 생성 → 바로 복사 → 메모장이나 비밀번호 관리 앱에 저장

용어 풀이: Region 한 문장 뜻 — 내 서버 데이터가 실제로 보관되는 지역이다. 일상 비유 — 택배 물류센터다. 우리 집(서울)에서 가까운 센터를 골라야 배송(응답)이 빠르다.

3단계 — 이메일 로그인 켜기 프로젝트가 다 만들어지는 데 10분쯤 걸린다. 다 되면 Authentication(인증) → Sign In / Providers → Email을 고른다. 여기서 "Confirm Email" 토글을 OFF(끔)로 바꾸고 Save(저장)한다.

용어 풀이: Confirm Email 한 문장 뜻 — 가입할 때 "메일함을 열어 인증 링크를 누르세요"를 요구하는 기능이다. 일상 비유 — 택배 받을 때 본인 확인 문자를 받는 것과 비슷하다. 편하지만 매번 번거롭다.

왜 끄냐고? 개발 중에는 회원가입을 수십 번 테스트한다. 매번 메일을 열어 인증 링크를 누르면 너무 번거롭다. 게다가 Supabase 무료 플랜은 인증 메일을 한 시간에 2개까지만 보내준다(원서/노트 기준 예시이며, 최신 값은 공식 문서에서 확인). 그래서 개발 단계에서는 끄고, 인증 없이 바로 가입되게 한다.

잘못된 예: Confirm Email 켠 채로 가입 테스트 → 메일 2개 보내고 한도 초과로 막힘 올바른 예: 개발 중엔 OFF → 마음껏 가입 테스트 → 나중에 진짜 서비스할 때 다시 ON 고려

4단계 — 연결 정보 가져오기 화면 위쪽의 Connect 버튼을 누른다. App Frameworks 탭에서 Next.js를 고른다. 그러면 두 가지 값이 보인다. NEXT_PUBLIC_SUPABASE_URL (주소) NEXT_PUBLIC_SUPABASE_ANON_KEY (열쇠) 둘 다 복사해서 .env.local 파일에 저장해 둔다(이 파일에 넣는 방법은 섹션 3에서 다룬다).

용어 풀이: Anon Key 한 문장 뜻 — 내 앱이 Supabase에 접속할 때 보여주는 공개용 열쇠다. 일상 비유 — 건물 1층 로비를 드나들 수 있는 방문자 카드 같은 것이다. 들어는 가지만 아무 데나 못 들어간다.

용어 풀이: .env.local 한 문장 뜻 — 주소나 열쇠 같은 민감한 값을 코드와 분리해 보관하는 설정 파일이다. 일상 비유 — 비밀번호를 코드 본문에 적지 않고 따로 적어 둔 메모지다.

한 걸음 더 ▸ Supabase는 Firebase와 뭐가 다를까

비슷한 서비스로 Firebase가 있다(구글이 만든 것). 지금 단계에선 몰라도 된다. 궁금한 사람만 보자.

한 줄로 정리하면, Supabase는 "표(엑셀)처럼 정돈된 데이터"에 강하고 공개되어 있어서 자유롭다.

직접 만들기 vs Supabase, 뭐가 다를까

왜 빌려 쓰는 게 나은지 표로 보자.

직접 만들면 배우는 건 많지만 시간이 오래 걸리고 실수하기 쉽다. 빌려 쓰면 빠르고 안전하다. 그래서 이번 장은 빌려 쓰는 길을 택한다.

용어 풀이: Auth 한 문장 뜻 — 로그인, 회원가입 같은 "본인 확인" 기능을 통틀어 부르는 말이다(authentication의 줄임). 일상 비유 — 건물 입구의 출입 통제 시스템이다.

2. 클로드가 최신 사용법을 보게 돕자 — Context7 MCP

이런 적 있죠?

클로드에게 코드를 부탁했는데 "옛날 방식"으로 짜 주는 바람에 에러가 난 적 있을 것이다. "분명 시키는 대로 했는데 왜 안 되지?" 하고 막힌다. 이유는 단순하다. 클로드는 과거 어느 시점까지의 자료로 학습했다. 그 뒤에 Supabase가 사용법을 바꿨다면, 클로드는 바뀐 걸 모를 수 있다.

그게 바로 Context7 MCP가 필요한 이유다.

용어 풀이: Context7 MCP 한 문장 뜻 — 여러 라이브러리의 최신 공식 문서를 모아 두었다가 클로드에게 실시간으로 보여주는 도우미다. 일상 비유 — 시험 볼 때 옆에서 최신판 교과서를 펼쳐 주는 조교다. 클로드는 옛날 노트가 아니라 최신 교과서를 보고 답한다.

용어 풀이: MCP 한 문장 뜻 — 클로드 코드에 외부 도구나 자료를 붙이는 표준 연결 방식이다(Model Context Protocol). 일상 비유 — 콘센트 규격이다. 규격만 맞으면 어떤 도구든 꽂아 쓸 수 있다.

비유를 클로드 코드에 연결하면

따라 하기 — Context7 설치하고 확인하기

터미널에 명령 한 줄이면 설치된다.

claude mcp add context7 -- npx -y @upstash/context7-mcp

성공하면 이런 메시지가 뜬다.

Added stdio MCP server context7 with command: npx -y @upstash/context7-mcp
to local config

설치만 하고 끝내면 안 된다. 정말 연결됐는지 확인하자. 클로드 코드 안에서 /mcp 라고 입력한다.

/mcp

목록에 context7 옆에 connected(연결됨) 표시가 보이면 성공이다.

잘못된 예: 설치 명령만 치고 바로 코드 작업 시작 → 사실 연결이 안 됐는데 모름 올바른 예: 설치 → /mcp 로 connected 확인 → 그다음 코드 작업

한 걸음 더 ▸ 출처가 궁금하면

Context7의 공식 깃허브는 github.com/upstash/context7 이다. 어떤 도구를 쓸 땐 만든 곳의 공식 저장소를 한 번 보는 습관이 좋다.

3. 클로드에게 "선 넘지 마"라고 말하자 — 경계 정해 로그인 만들기

이런 적 있죠?

클로드에게 "로그인 기능 만들어 줘"라고만 했더니 부탁하지도 않은 소셜 로그인까지 붙이고, 멀쩡한 파일까지 고쳐 버린 적 있을 것이다. "왜 시키지도 않은 걸 했지?" 하고 당황한다.

클로드는 혼자서도 충분히 코딩을 잘한다. 문제는 너무 잘해서, 선을 안 그어 주면 멀리까지 가 버린다는 점이다. 그래서 일을 시킬 땐 경계(선)를 분명히 그어 줘야 한다.

용어 풀이: 경계 설정 한 문장 뜻 — "여기까지만 해, 이건 하지 마"라고 작업 범위를 미리 정해 주는 것이다. 일상 비유 — 인테리어 기사에게 "거실만 칠하고 안방은 손대지 마세요"라고 미리 못 박는 것과 같다.

비유를 클로드 코드에 연결하면

따라 하기 — 2단계로 시킨다 (계획 먼저, 실행 나중)

핵심은 한 번에 "만들어 줘"가 아니라, 계획 받고 → 확인하고 → 실행이다.

1단계 프롬프트 — 계획만 부탁하기

Supabase Auth를 연동하려고 해.
- 소셜 로그인은 추가하지 않을거야 이메일 로그인만 사용할 거야.
- SSR이 지원되는 형태로 계획을 알려줘.
- 실제 코드는 아직 작성하지 말고 어떻게 해야 하는지 알려주기만 해.
- context7을 사용해서 최신 Supabase 사용법을 알아봐줘.

이 한 덩어리 안에 경계가 네 개나 들어 있다. "소셜 로그인 빼" (기능 범위) "SSR 방식" (구현 방식) "코드는 아직 쓰지 마" (계획과 실행 분리) "context7 써서 최신으로" (도구 지정)

용어 풀이: SSR 한 문장 뜻 — 화면을 서버에서 미리 완성해 보내 주는 방식이다(Server-Side Rendering). 일상 비유 — 식당에서 요리를 다 만들어 접시째 내오는 것이다. 손님(브라우저)이 주방에서 직접 조리할 필요가 없다. 로그인 같은 민감한 일은 이렇게 서버에서 처리하는 게 안전하다.

클로드는 대략 이런 계획을 내놓는다.

1. @supabase/ssr 패키지 사용 - 최신 SSR 전용 패키지
2. Cookie 기반 세션 관리 - getAll/setAll 방식으로 쿠키 처리
3. Next.js App Router 방식 - Server Components와 Server Actions 활용
4. Middleware 인증 보호 - 전역 인증 상태 관리

용어 풀이: 쿠키(Cookie) 한 문장 뜻 — 브라우저에 저장해 두는 작은 메모로, "이 사람 로그인했음" 같은 표시에 쓴다. 일상 비유 — 놀이공원 손목띠다. 한 번 받으면 재입장할 때 매번 표 안 끊어도 된다.

용어 풀이: 세션(Session) 한 문장 뜻 — "지금 로그인 상태가 유지되고 있다"는 정보 묶음이다. 일상 비유 — 손목띠를 차고 있는 동안의 "입장 중" 상태다. 띠가 풀리면(로그아웃) 세션도 끝난다.

용어 풀이: Middleware 한 문장 뜻 — 페이지에 도착하기 전에 먼저 거쳐 가며 검사하는 중간 단계다. 일상 비유 — 건물 입구의 경비실이다. 모든 방문자가 일단 여기를 지나며 출입증을 확인받는다.

용어 풀이: Server Actions 한 문장 뜻 — 폼 제출 같은 일을 서버에서 바로 처리해 주는 Next.js 기능이다. 일상 비유 — 민원 창구다. 신청서를 내면 그 자리에서 담당자가 처리해 준다. 별도 우편 절차가 필요 없다.

2단계 프롬프트 — 계획대로 실행 지시하기 계획이 마음에 들면 이제 실행을 시킨다.

현재 계획한 플랜을 기반으로 작업을 실행해줘.
우리 계획을 벗어나는 작업은 절대로 하지 말고
작업이 끝나면 어떤 작업들을 했는지 분석해서 알려줘.

여기서도 "계획을 벗어나는 작업은 절대로 하지 마"라고 한 번 더 선을 긋는 게 핵심이다.

클로드가 만드는 파일들 (대략 이런 게 생긴다)

겁먹을 필요 없다. 무슨 일을 하는 파일인지만 알면 된다.

프로젝트/
├── .env.local              ← 주소와 열쇠를 적어 두는 곳
├── middleware.ts           ← 입구 경비실 (로그인 검사)
├── src/
│   ├── utils/supabase/
│   │   ├── server.ts       ← 서버용 Supabase 연결 도구
│   │   ├── client.ts       ← 브라우저용 Supabase 연결 도구
│   │   └── middleware.ts   ← 경비실용 연결 도구
│   ├── app/
│   │   ├── login/
│   │   │   ├── page.tsx    ← 로그인/회원가입 화면
│   │   │   └── actions.ts  ← 로그인/회원가입 실제 처리
│   │   ├── register/
│   │   │   └── page.tsx    ← 회원가입 화면
│   │   ├── auth/callback/
│   │   │   └── route.ts    ← 이메일 인증 후 돌아오는 길 처리
│   │   └── error/
│   │       └── page.tsx    ← 에러 화면
│   └── components/
│       ├── auth/UserMenu.tsx    ← "로그인한 사람" 메뉴
│       └── layout/Header.tsx    ← 상단 바에 로그인 상태 표시

클로드가 실제로 한 일 목록

실행이 끝나면 클로드가 한 일을 정리해서 알려 준다. 대략 이렇다.

1. 환경 설정      - .env.local 파일 만들기 (주소/열쇠 자리 마련)
2. 패키지 설치    - @supabase/supabase-js, @supabase/ssr 설치
3. 연결 도구 3종  - server.ts, client.ts, middleware.ts
4. 경비실 설정    - middleware.ts (전체 로그인 검사)
5. 인증 화면      - login/page.tsx, register/page.tsx
6. 실제 처리      - login/actions.ts (로그인/회원가입 동작)
7. 콜백 처리      - auth/callback/route.ts, error/page.tsx
8. 로그인 표시    - UserMenu.tsx, Header.tsx

용어 풀이: 패키지(Package) 한 문장 뜻 — 남이 만들어 둔 코드 묶음으로, 설치해서 가져다 쓰는 것이다. 일상 비유 — 밀키트다. 재료 손질이 끝난 상태로 받아서 바로 조리만 하면 된다.

왜 연결 도구가 세 개나 필요할까

server.ts, client.ts, middleware.ts — 비슷해 보이는데 왜 셋으로 나눌까? 환경마다 쿠키를 다루는 방식이 다르기 때문이다.

하나로 합치면 어떻게 될까? 서버에서 브라우저 전용 기능을 부르면 에러가 난다. 환경마다 안전 규칙이 달라서, 섞으면 보안이 무너진다. 그래서 셋으로 나눈다. 지금은 "환경마다 다르니까 나눈다" 정도만 기억하면 충분하다.

한 걸음 더 ▸ 흔히 막히는 두 곳

여기는 실제로 자주 막히는 부분이라 미리 짚어 둔다.

첫째, .env.local은 클로드가 안 채워 줄 수 있다. 이 파일엔 진짜 열쇠가 들어가는데, 민감한 값이라 클로드가 일부러 손대지 않을 수 있다. 그땐 섹션 4처럼 내가 직접 값을 넣어 줘야 한다.

둘째, 열쇠 이름이 다르게 생겼을 수 있다. Supabase가 주는 키 이름과 클로드가 코드에 쓴 키 이름이 다를 수 있다. 이럴 땐 그냥 클로드에게 "환경변수 키 이름 알려 줘"라고 물으면 맞는 이름을 알려 준다.

용어 풀이: 환경변수 한 문장 뜻 — .env.local 안에 "이름 = 값" 형태로 적어 두는 설정값이다. 일상 비유 — 사물함 이름표다. 이름(NEXT_PUBLIC_SUPABASE_URL)을 부르면 그 안의 값(실제 주소)이 나온다.

4. 만든 게 잘 도는지 확인하자 — 열쇠 넣고 서버 켜기

이런 적 있죠?

코드는 다 만들었는데 로그인 버튼을 눌러도 안 된 적 있을 것이다. "클로드가 다 만들었다는데 왜 안 되지?" 하고 막힌다. 대부분 이유는 하나, 진짜 열쇠를 아직 안 넣었기 때문이다.

출입 시스템(코드)은 다 설치됐지만, 정작 문을 열 열쇠(URL과 Key)가 비어 있는 셈이다.

비유를 클로드 코드에 연결하면

따라 하기 — 값 넣고 재시작하기

1단계 — .env.local에 값 채우기 섹션 1의 4단계에서 복사해 둔 두 값을 넣는다.

NEXT_PUBLIC_SUPABASE_URL=여기에_복사한_주소
NEXT_PUBLIC_SUPABASE_ANON_KEY=여기에_복사한_열쇠

잘못된 예: 따옴표나 공백을 잘못 넣음, 한 줄에 두 값을 붙여 씀 올바른 예: 한 줄에 하나씩, 등호(=) 뒤에 값만 깔끔하게

2단계 — 서버 껐다 켜기 환경변수는 서버가 켜질 때 한 번 읽는다. 그래서 값을 바꾼 뒤엔 반드시 서버를 껐다가 다시 켜야 새 값이 반영된다.

이럴 때 이렇게 — 값을 다 넣었는데도 로그인이 안 되면, 먼저 서버를 재시작했는지부터 확인하자. 안 했다면 그게 원인일 때가 많다.

3단계 — 동작 확인하기 서버를 다시 켰을 때 오류 메시지가 없으면 일단 성공이다. 이제 회원가입을 해 보고, 그 계정으로 로그인이 되는지 눌러 본다. 로그인하면 상단 바(Header)에 내 정보가 뜨고, 로그인 안 한 사람은 자동으로 로그인 페이지로 보내진다.

용어 풀이: 리다이렉트(Redirect) 한 문장 뜻 — 어떤 페이지에 들어오면 자동으로 다른 페이지로 보내는 것이다. 일상 비유 — 출입증 없이 들어오려는 사람을 경비가 "저쪽 안내데스크로 가세요"라며 돌려보내는 것이다.

한 걸음 더 ▸ 로그인 검사는 어떻게 일어날까

서버 화면에서는 getUser() 라는 기능으로 "지금 이 사람 누구지?"를 확인한다. 로그인 안 한 사람이면 자동으로 로그인 페이지로 리다이렉트한다. 지금은 "로그인 안 한 사람은 알아서 쫓아내 준다" 정도만 알면 된다.

용어 풀이: getUser() 한 문장 뜻 — 현재 로그인한 사용자가 누구인지 알려 주는 기능이다. 일상 비유 — 경비가 출입증을 보고 "아, OO님이시군요" 하고 신원을 확인하는 것이다.

이번 장 한눈에 정리

핵심 습관 세 가지만 가져가자. 하나, 만들 수 있어도 빌릴 수 있으면 빌린다(Supabase). 둘, 클로드에게 일 시킬 땐 항상 선을 그어 준다(경계 설정). 셋, 안 되면 먼저 "내가 빠뜨린 단계"부터 의심한다(열쇠, 재시작).

스스로 점검하기

1. 로그인 같은 서버 기능을 직접 안 만들고 빌려 쓰는 서비스 이름은 무엇인가? 그리고 그게 좋은 이유 한 가지를 말해 보자.

2. 클로드가 옛날 방식으로 코드를 짜는 걸 막으려고 붙이는 도우미는 무엇이고, 설치 후 연결을 확인하는 명령어는 무엇인가?

3. 클로드에게 로그인 구현을 시킬 때 "계획 먼저, 실행 나중" 2단계로 나누면 좋은 점은 무엇인가?

4. .env.local에 값을 넣었는데도 로그인이 안 된다. 가장 먼저 확인할 것은 무엇인가?

(힌트: 1번은 섹션 1, 2번은 섹션 2, 3번은 섹션 3, 4번은 섹션 4를 다시 보면 된다.)

다음 장 예고: 다음 장에서는 만든 기능을 더 다듬어 본다. 지금 몰라도 된다.